---
title: sdk/client
description: Client Side Functions
next: false
---

The `rwsdk/client` module provides a set of functions for client-side operations.

## `initClient`

The `initClient` function is used to initialize the React Client. This hydrates the RSC flight payload that's add at the bottom of the page. This makes the page interactive.

## `initClientNavigation`

The `initClientNavigation` function is used to initialize the client side navigation. An event handler is assocated to clicking the document. If the clicked element contains a link, href, and the href is a relative path, the event handler will be triggered. This will then fetch the RSC payload for the new page, and hydrate it on the client.

## `ClientNavigationOptions`

`initClientNavigation()` accepts an optional **`ClientNavigationOptions`** object that lets you
control how the browser scrolls after each navigation:

| Option           | Type                              | Default     | Description                                                                                                                                                                              |
| ---------------- | --------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scrollToTop`    | `boolean`                         | `true`      | Whether to scroll to the top of the page after a successful navigation. Set it to `false` when you want to preserve the existing scroll position (for example, an infinite-scroll list). |
| `scrollBehavior` | `'instant' \| 'smooth' \| 'auto'` | `'instant'` | How the scroll _happens_ when `scrollToTop` is `true` (ignored otherwise).                                                                                                               |
| `onNavigate`     | `() => Promise<void> \| void`     | —           | Callback executed **after** the history entry is pushed but **before** the new RSC payload is fetched. Use it to run custom analytics or side-effects.                                   |

### Usage Examples

```tsx title="Default behaviour – jump to top instantly"
import { initClientNavigation } from "rwsdk/client";

initClientNavigation();
```

```tsx title="Smooth scrolling to top"
initClientNavigation({
  scrollBehavior: "smooth",
});
```

```tsx title="Preserve scroll position"
initClientNavigation({
  scrollToTop: false,
});
```

```tsx title="Custom onNavigate logic"
initClientNavigation({
  scrollBehavior: "auto",
  onNavigate: async () => {
    // e.g. send page-view to analytics before RSC fetch starts
    await myAnalytics.track(window.location.pathname);
  },
});
```

### Rationale & Defaults

RedwoodSDK mirrors the behaviour of classic Multi Page Apps where each link click
brings you back to the **top** of the next page. This is the most common
expectation and is therefore the default. You can turn it off or make it smooth
with a single option – no additional libraries required.

## `navigate`

The `navigate` function is used to programmatically navigate to a new page. It
accepts a `href` parameter (the destination URL) and an optional `options` object.

| Option                 | Type                              | Default     | Description                                                                                              |
| ---------------------- | --------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------- |
| `history`              | `'push' \| 'replace'`             | `'push'`    | Determines how the history stack is updated. `'push'` adds a new entry, `'replace'` replaces the current one. |
| `info.scrollToTop`     | `boolean`                         | `true`      | Whether to scroll to the top of the page after navigation.                                              |
| `info.scrollBehavior`  | `'instant' \| 'smooth' \| 'auto'` | `'instant'` | How the scroll happens when `scrollToTop` is `true`.                                                     |

### Usage Examples

```tsx title="Basic navigation"
import { navigate } from "rwsdk/client";

navigate("/about");
```

```tsx title="Navigation with replace"
import { navigate } from "rwsdk/client";

navigate("/profile", { history: "replace" });
```

```tsx title="Navigation with smooth scroll"
import { navigate } from "rwsdk/client";

navigate("/dashboard", {
  info: {
    scrollBehavior: "smooth",
  },
});
```
